Scripting
Documentation
Changelog
Privacy
Documentation
Changelog
Privacy

Query Statistics Collection PRO

Requires Scripting PRO

The Health.queryStatisticsCollection() method retrieves time-based aggregated statistics for a given HealthQuantityType over a specified date range. It returns a HealthStatisticsCollection object, which contains multiple HealthStatistics entries aligned to defined time intervals (such as daily, weekly, or monthly).

This method is ideal for analyzing trends, building charts, and generating historical summaries of health data.

Method Signature

1function queryStatisticsCollection(
2  quantityType: HealthQuantityType,
3  options: {
4    startDate?: Date
5    endDate?: Date
6    strictStartDate?: boolean
7    strictEndDate?: boolean
8    statisticsOptions?: HealthStatisticsOptions | Array<HealthStatisticsOptions>
9    anchorDate: Date
10    intervalComponents: DateComponents
11  }
12): Promise<HealthStatisticsCollection>

Parameters

Name Type Required Description
quantityType HealthQuantityType Yes The health quantity type to query (e.g., "stepCount", "heartRate").
options.startDate Date No The start date of the time range. Samples outside this range will be excluded.
options.endDate Date No The end date of the time range.
options.strictStartDate boolean No If true, includes only statistics whose interval starts exactly at startDate.
options.strictEndDate boolean No If true, includes only statistics whose interval ends exactly at endDate.
options.statisticsOptions HealthStatisticsOptions[] or single option No The list of statistics to compute. Can include: "cumulativeSum", "discreteAverage", "discreteMin", "discreteMax", "mostRecent", "duration", "separateBySource"
options.anchorDate Date Yes The anchor date used to align intervals. For example, use midnight to align daily intervals to calendar days.
options.intervalComponents DateComponents Yes Defines the interval for grouping data (e.g., day, week, month). Create using new DateComponents({ day: 1 }), etc.

Return Value

Returns a Promise that resolves to a HealthStatisticsCollection object. This collection includes statistics for each time interval between the start and end dates, aligned by the anchor date and grouped using the provided intervalComponents.

Example: Retrieve Daily Step Count Statistics for the Past 7 Days

1const now = new Date()
2const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000)
3
4const collection = await Health.queryStatisticsCollection("stepCount", {
5  startDate: sevenDaysAgo,
6  endDate: now,
7  anchorDate: new Date(), // typically midnight today
8  intervalComponents: new DateComponents({ day: 1 }),
9  statisticsOptions: ["cumulativeSum"]
10})
11
12const stats = collection.statistics()
13for (const stat of stats) {
14  const steps = stat.sumQuantity(HealthUnit.count())
15  console.log(`From ${stat.startDate.toDateString()}: ${steps} steps`)
16}

Notes

  • If no data exists for a specific interval, its corresponding HealthStatistics entry may return null values.
  • Intervals are aligned using the anchorDate, and the grouping is defined by intervalComponents.
  • If you only need overall statistics for the full range without interval grouping, use Health.queryStatistics() instead.
Outline